Internet Info 1994 March

home *** CD-ROM | disk | FTP | other *** search

/ Internet Info 1994 March / Internet Info CD-ROM (Walnut Creek) (March 1994).iso / networking / terms / kermit / c / ql2ker.doc < prev next >

Wrap

Text File | 1988-08-16 | 19.6 KB | 507 lines

File QL2KER.DOC --------------- Kermit for the Sinclair QL -------------------------- AUTHOR : David Harper Dept of Applied Maths and Theoretical Physics The University P.O. Box 147 Liverpool L69 3BX EMAIL : SX36 at UK.AC.LIVERPOOL.IBM OPERATING SYSTEM : QDOS (Sinclair QL and derivatives) LANGUAGE : BCPL (Metacomco) DATE : 29 May 1987 (1) Generating the EXECable program This version of QL Kermit is written in BCPL and should be compiled using Metacomco's BCPL Development Kit There are four source files. They should be renamed as follows (assuming that you have disc drives - if not, change FLP to MDV). File QDOS name Purpose QL2KER.BCP FLP2_KERMAIN_BCPL Command parser & executive QL2SET.BCP FLP2_KERSET_BCPL Handles the SET command QL2PRO.BCP FLP2_KERPROTO_BCPL Kermit protocol routines QL2HDR.BCP FLP2_KERHDR Header file - defines globals and manifest constants The header file is imbedded in each of the other three files using the BCPL GET directive. Within KERMAIN, KERSET and KERPROTO it is referred to as FLP2_KERHDR so if you are using microdrives, you should edit each of the three files and change the line GET "FLP2_KERHDR" to GET "MDV2_KERHDR" To construct the EXECable program, compile the files KERMAIN, KERSET and KERPROTO then use the linker 'BLINK' to join their object code files together. The result is a program which can be run under QDOS in tandem with other tasks, using QDOS's multi-tasking capability. I use the name FLP2_KERMIT_EXE for the EXECable file. ***** NOTE : Metacomco BCPL Development Kit versions 1.nn ***************** * * * If you don't have a copy of version 2.0 (or later) of Metacomco's * * BCPL compiler, you will need to assemble the file 'qtrap_asm' and * * link it with the other object code files. You should alter the * * header file 'kerhdr' to include a suitable global reference to qtrap. * * Dr Alex Finch's version of qtrap has global number 276 so you should * * include * * * * GLOBAL $( qtrap : 276 $) * * * * in 'kerhdr' at some point, or add it to the existing global list. * * * * Versions from 2.0 have qtrap as part of the BCPL library at global 101 * * and so they don't require this extra file. * * * *************************************************************************** (2) Running Kermit To run the task, use EXEC FLP2_KERMIT_EXE You can use EXEC_W if you prefer, but Kermit will run quite happily alongside other tasks as long as they don't demand too large a share of processor time. Besides, since Kermit doesn't support QDOS commands such as DIR, it is useful to be able to switch to SuperBasic for a moment to issue such commands directly. This doesn't interfere with Kermit in any way, and you can even do it while Kermit is engaged in file-transfer. When Kermit is expecting a command, you will see the prompt QL-Kermit (Local) > and the cursor should be flashing just after the '>'. (If the cursor is somewhere else on the screen, e.g. the SuperBasic command window, use Control-C to switch between tasks until the Kermit cursor begins to flash.) (3) Kermit commands Kermit recognises the following commands : HELP Lists all recognised commands, with any operands. HELP SET List all the settable options EXIT ) End the Kermit task i.e. remove it from END ) QDOS SET <parameter> <value> Alter one of the settable options - see next section. SHOW Show the values of some of the settable options. SERVER Enter server mode operation CONNECT Open the serial communication line DISCONN Close the serial communication line (use this when you wish to change the line attributes e.g. parity) TAKE <local filename> Take Kermit commands from a file SEND <local-file> <remote-file> Send a file to a remote Kermit GET <remote-file> <local-file> Fetch a file from a remote serving Kermit RECEIVE <local-file> Receive a file from a remote Kermit FINISH Issue a FINISH command to a remote serving Kermit. (4) Options of the SET command The SET command recognises the following options. (*) means that I haven't yet implemented this option e.g. block-check type. Items in square brackets [ ... ] are optional. N is any non-negative number. CHAR is a single character. Option Values Notes ------ ------ ----- BLOCK-CHECK (*) DEBUG ON [filename] | OFF [CLOSE] See note 2 DELAY N (less than 60) 8BIT-PREFIX ON | OFF Do we do 8th-bit prefixing END-OF-LINE CR | LF The character we recognise as end-of-line ESCAPE-CHAR F1 | F2 | F3 | F4 | F5 | Key to escape from terminal ESC | CTRL-ESC emulation back to Kermit command mode FLOW-CONTROL (*) HANDSHAKE CTS | XON | NONE Type of handshaking to do with the other Kermit. See note 3. LOG (*) MARKER N (0 <= N < 27) Start-of-packet character PACKET-LENGTH N (30 < N < 93) Largest packet we want to receive PADDING N Number of padding chara- cters we need to receive PAD-CHAR N (0 <= N < 32) The padding character we need to receive PARITY EVEN | ODD | MARK | SPACE | See note 4 NONE PAUSE N PREFIX CHAR The character we propose to use for 8th-bit prefix REPEAT-COUNT (*) RETRY N Our retry threshold TIMEOUT N Interval after which we should be timed-out LINE 1 | 2 To select port SER1 or SER2 See note 5 DIR (*) OVERWRITE (*) BAUD 75 | 150 | 300 | 600 | 1200 | Baud rate. See note 6 2400 | 4800 | 9600 TERMINAL-TYPE (*) INTERFACE NONE | RAW | QCONNECT Type of interface hardware in use. See note 1. TAKE-ECHO ON | OFF Whether we echo commands from TAKE files to the screen. Notes ----- 1. Kermit includes routines to enable it to communicate via the Tandata QConnect communications module. This 'little black box' is particularly useful in implementing XON/XOFF handshaking to allow the QL to work with mainframes and packet-switch systems (eg Gandalf PACX) that simply don't use hardware CTS/RTS handshaking. The QL's serial ports only have CTS/RTS capability, and I haven't written any cunning XON/XOFF-handling code into Kermit. So if your mainframe uses XON/XOFF, a QConnect box might be a good investment. As an added bonus, it comes with a rather good VT100 emulator - Kermit only has glass-teletype at the moment ! 2. The debugging facility writes out details of each packet as it is received or sent, plus timeouts (if they occur) and each attempt to open a file. By default, debugging reports are sent to the screen and may be enabled using SET DEBUG ON and disabled using SET DEBUG OFF. However, if you wish to direct the reports to a file, use the form SET DEBUG ON file-name After this, SET DEBUG ON/OFF enables or disables reporting to that file, which remains open. To close a debugging file, use SET DEBUG OFF CLOSE This closes the current debugging file (unless debugging is to the screen - we don't want to close the screen channel !) and disables debugging. A subsequent SET DEBUG ON will output to the screen. You may open a new debugging file without closing the previous one. For example SET DEBUG ON flp2_debug_file1 ... ... ... SET DEBUG ON flp2_debug_file2 In this case, flp2_debug_file1 will still be open but Kermit has forgotten its channel ID so it can't close it. It will remain open until you stop the Kermit job, whereupon QDOS closes all outstanding open files as part of its housekeeping. 3. In the absence of a Tandata QConnect module (Note 1 above), the option SET HANDSHAKE XON cannot be honoured, so you shouldn't use it. When using raw (i.e. no little black boxes) communications, choose CTS or NONE. 4. The Tandata QConnect box cannot operate using MARK or SPACE parity. 5. The QL has two RS232 ports, SER1 and SER2. One of them is configured as DTE and the other as DCE. In practical terms this means that you should use SER2 (SET LINE 2) if you want to communicate with a mainframe and SER1 (SET LINE 1) if you are Kermitting with another micro which thinks that it is a terminal. The Tandata QConnect box will only plug in to SER2, so SET INTERFACE QCONNECT and SET LINE 2 must be issued together. When I link my QL with a BBC micro, the Beeb's RS423 socket is connected to the the QL's SER1 socket (via two adaptor leads and a female-female gender changer - why do I use two micros that have non-standard serial comms hardware ?!). 6. The QL supports these baud rates : 75, 300, 600, 1200, 2400, 4800, 9600 If you are using a Tandata QConnect box, the baud rates are 150, 300, 600, 1200, 2400, 4800, 9600 (5) General notes about using Kermit TERMINAL EMULATION Most people will want to use Kermit to transfer files to/from mainframes. A simple teletype terminal-emulator is included to allow you to call the remote system. If you are using a QConnect box, don't worry about the strange message which appears (in red) when you issue the CONNECT command. It is simply telling you the command string which it has sent to QConnect to set up the connection. The terminal emulator will print out any ASCII character in the range 32 to 126. It interprets a CRLF sequence from the remote system as a single LF, which is the QDOS newline character. Backspace (ASCII 08 dec) moves the cursor one space to the left and formfeed (ASCII 12 dec) clears the screen. Bell (ASCII 07 dec) causes the message '<beep>' to appear (in red) on the screen. Any other character in the range 0 to 31 is displayed in the form '<#Xnn>' where nn is the hexadecimal representation of the number. As far as Bell is concerned, I will probably make this trigger the QDOS BEEP routine in the next release. The QL sends all ASCII characters from 0 to 127 (though ASCII 03, CTRL-C, can never be sent because it is the key used by QDOS to switch from one task to another). The cursor keys and function keys are ignored, except for Left and CTRL-Left which both generate ASCII DEL (127 dec) - so CTRL-Left can be used as the delete key just as it is during QDOS buffered terminal input. The key to be used to escape from terminal emulation back to Kermit command mode can be altered using the SET ESCAPE option. To begin with, it is the ESC key, but your mainframe might require that you use this key so the next best alternative is probably F1 or one of the other function keys. FILE TRANSFER The status reports during file transfer are fairly basic. Kermit prints a message to indicate that it is sending/receiving a file, with the name of the file. During transfer, it prints a full-stop '.' after every 5th packet it receives successfully, but for every packet which it fails to receive (either because it timed out, or because the received packet was incorrect in some way) it prints out a percent symbol '%' A successful file transfer might look like this : QL-Kermit (Local) > RECEIVE flp2_datafile1 Receiving file flp2_datafile1 ...................... QL-Kermit (Local) > while a transfer which suffered one or two hiccups might appear as QL-Kermit (Local) > RECEIVE flp2_datafile1 Receiving file flp2_datafile1 .........%....%%....... QL-Kermit (Local) > Here, three errors occurred but since there are twenty full-stops, the average is three errors for 100 packets successfully received so it's not as alarming as it might appear. SERVER MODE Kermit can operate as a server. This is useful when transferring files to and from another micro. Kermit recognises two generic exit commands, FINISH and LOGOUT. FINISH returns Kermit to the state where it is waiting for input from the QL keyboard, while LOGOUT can be used to terminate the Kermit task from the other micro. Debugging can be carried out in server mode, and status reporting to the QL console screen is carried out as in non-server mode. TANDATA QCONNECT The QConnect device has a few idiosyncracies which affect Kermit. The technical information provided by Tandata in the user manual is brief and difficult to understand. Some of the things that the manual claims QConnect can do are in error - for example, the QL <-> QConnect serial line can only operate at 9600 baud. When the QConnect <-> remote line is working at a lower speed, this causes serious buffering problems inside the QConnect when the QL sends a burst of more than 20 bytes - in practise, this means that files can be received by QL-Kermit at any baud rate (when it only has to send short packets), but QL-Kermit can only send files via a QConnect at 9600 baud. At lower speeds, data packets become garbled as they pass through the QConnect. Terminal emulation works at lower speeds, however. Perversely, the terminal emulation code is a little slow and operation at 9600 baud sometimes encounters framing errors. I'm afraid that 4800 is the maximum reliable speed for terminal emulation, but file-transfer can only be done at 9600. This situation reflects a design flaw in the QConnect and I shall be taking it up with Tandata in the near future. I hope that a subsequent release of QL-Kermit will be able to make use of an improved QConnect ! FILES and QDOS Kermit doesn't (at present) do any clever file-name translation when it is in server mode and it receives a file name in an R or F packet from the other Kermit. So the other Kermit must use full QDOS filenames in its SEND and GET commands. I know that this is contrary to the guidelines on file nomenclature in the protocol since the file names must contain underscores - I'll amend the next release so that underscores can be replaced by full-stops. For example, flp2_data_file ought to be sent in an R or F packet as flp2.data.file Kermit will not overwrite an existing file - the transfer is abandoned as if the file name were unacceptable to QDOS. This is where it is particularly useful to multi-task Kermit so you can switch to SuperBasic to check the directory and delete files. I haven't tried to use Kermit with microdrives - it works very well with disc drives and RAMdisc, but I will include software buffering in the next release so that an entire file can be loaded into a buffer on the QL to avoid having to read repeatedly from microdrives. In an ideal world, QDOS would be able to do this automatically but the microdrives are notoriously slow. CATASTROPHES Kermit is still imperfect. I'm sure that users can find some way of crashing it - at least, I hope so because it means that I can (hopefully) correct the error. One or two QDOS errors will prove fatal to Kermit. For example, if it is unable to open a serial line (or to close it !), this will be detected in the software and Kermit will shut itself down with (usually) a message to explain why. Some catastrophes are unforeseen by the program, but they may be picked up by the BCPL run-time system. If this happens, the BCPL routine called ABORT is called (by BCPL itself, not by Kermit) and a traceback of all calling routines is printed to the screen. The most useful information here is the list of the routine names - they appear as the first (non- numeric) item on each line and are generally 7 characters long. (The run-time system only stores the first 7 characters of each routine name for the purpose of error tracing.) If Kermit stops with an error report, make a note of what is on the screen and (if possible) what Kermit was supposed to be doing when it failed. I'd be interested to hear about this. (On a slightly mischievous note : you can make the BCPL run-time system do an ABORT by typing ---- SET TAKE-ECHO ON This is a known bug, but I'm afraid I don't know how to solve it !) ACKNOWLEDGEMENTS (Not the Kermit kind !) Several individuals and companies have helped in the production of this Kermit and deserve credit. First of all, C.G.Selwyn wrote the original version for the Tripos operating system. I take responsibility for all of the errors I may have introduced into his program in the course of converting it to work under QDOS. My thanks to Mr Selwyn, and to Icarus Sparry of the Microcomputer Unit at Bath University who sent me the original program. Dr Alex Finch of the Physics Dept at Lancaster University wrote the assembler version of the routine 'qtrap' which is needed to compile Kermit using Metacomco's BCPL Development Kit prior to version 2.0 Thanks also to Tandata Marketing Ltd who provided me with the source code of their communications package which drives the QConnect device. Their programs helped me to understand how the device should be used with Kermit. Many thanks to Metacomco for sending me a pre-release copy of version 2.0 of their BCPL development system. This includes a very useful library routine for invoking QDOS traps directly. Finally, thanks to Mike Lewis of Liverpool University Computer Lab for arranging the loan of a line-monitor to me while I was trying to understand why the QL/QConnect couldn't send files properly. The line monitor proved to be a very useful tool.